What

The ecosystem CI-failure-reading primitive + its thin CLI verb scitex-dev ci why.

Final CLI path is scitex-dev ci why (top-level ci group, joining ci runner) — not ecosystem ci why. scitex-dev drops the redundant middle dev (that word is already its package name); downstream consumers surface it as <cli> dev ci why. (Branch name feat/ecosystem-ci-why kept as-is to avoid churning the PR.)

Reading CI status is one word (failure); reading why has been tens of thousands of lines, so a bounded-context agent gets steered to the cheap word and the word replaces the reason. This inverts the price: fetch a failing run's --log-failed once, distil it to a few hundred bytes.

The primitive (SSOT) — scitex_dev.ci.why

Importable by ANY project (sac, the umbrella, …), which supply only a thin verb over it:

from scitex_dev.ci.why import explain_ci_run, render_text

for run in explain_ci_run("712"):        # PR#, run id, branch, or None
    print(render_text(run))

• explain_ci_run(target, *, run_gh=None, repo=None) -> list[RunFailures] — a PR can front >1 failing run, hence a list.
• explain_run(run_id, ...) -> RunFailures, resolve_run_ids(target, ...) -> list[str]
• Parser helpers (pure, network-free): clean_log_line, split_log_by_job, parse_job_context, parse_failed_log — four tiers: pytest short test summary FAILED ids -> FAILURES block E lines -> ##[error] annotations -> tail fallback.
• Injectable run_gh gh-seam (the only network touch) + CIWhyError (UNKNOWN is raised loudly, never swallowed into a reassuring "no failures").

The CLI verb

scitex-dev ci why <target> — the why verb attached to the existing top-level ci group, alongside ci runner (both coexist; runner is untouched). --json, -R/--repo. Tri-state exit: 0 green / 1 red (reason printed) / 2 could-not-read.

Watch it fail (real live runs)

scitex-dev run 29312551895 (workflow tests) — pytest tier, all 3 matrix legs:

pytest-matrix-on-ubuntu-py3.11 (py3.11, ubuntu)
  FAILED tests/develop/test_audit.py::test_audit_all_clean - AssertionError: audit-all reported violations for 'scitex-dev' (exit=1).
  E           AssertionError: audit-all reported violations for 'scitex-dev' (exit=1).
  -> https://github.com/scitex-ai/scitex-dev/actions/runs/29312551895/job/87019303421

sac run 29446283736 (workflow quality, a setup failure with no pytest) — ##[error] tier:

scitex-dev-quality-audit-on-ubuntu-latest (ubuntu-latest)
  ##[error] error: could not lock config file .../.gitconfig: File exists
  ##[error] fatal: no submodule mapping found in .gitmodules for path '.tmp-audit/scitex-browser'
  ##[error] Unknown system error -116: ... copyfile ... uv

Both extract the reason, not the whole log.

Tests — no mocks

• Parser off real-shaped GitHub-Actions log STRINGS (pytest-failure log + a ##[error] setup-failure log).
• Resolver + explain_* through an injected run_gh callable (offline).
• CLI end-to-end against a real fake gh on PATH (a real subprocess; PATH restored, no monkeypatch — PA-306). A coexistence test asserts ci runner and ci why both resolve.

Full slice green (156 passed — the new primitive/CLI tests plus the pre-existing ci/runner suite and the ecosystem registry/categories regression).

Notes

• Lifted generically from sac's shipped _ci_why.py — no sac specifics.
• Orthogonal to open PRs feat(audit): PS-169 — GitHub-hosted runners are forbidden, no exceptions #344 (audit hosted-runners), ci: migrate to scitex-ai/.github reusable workflows #316 (.github/workflows reusable migration), fix(ci-template): isolate per-job git global config to stop ~/.gitconfig lock collisions #314 (ci_template templates) — zero file overlap; this only READS logs.
• Line-limit audit clean (largest file 254 lines). audit-cli flags only PRE-EXISTING free-form-help commands (ci runner, linter, ecosystem dashboard); the new ci why is spec-built and passes.